package com.zyl.blog.processing.service;

import com.github.yulichang.base.MPJBaseService;
import com.zyl.blog.common.domain.file.bean.FileStorage;
import com.zyl.blog.common.domain.file.dto.FileUploadResponse;
import org.springframework.core.io.Resource;
import org.springframework.web.multipart.MultipartFile;

import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;

/**
 * @version v1.0
 * @ProjectName: Personal_Blog_Server
 * @Package: com.zyl.blog.processing.service
 * @ClassName: FileStorageService
 * @Description: 文件存储服务
 * @Author FinalFantasy
 * @Date 2025/8/14-13:24
 */
public interface FileStorageService extends MPJBaseService<FileStorage> {

    /**
     * 上传文件（单文件）
     * @param file 上传的文件
     * @param uploaderId 上传者ID
     * @param description 文件描述
     * @return 上传结果
     */
    FileUploadResponse uploadFile(MultipartFile file, Long uploaderId, String description);

    /**
     * 异步上传文件
     * @param file 上传的文件
     * @param uploaderId 上传者ID
     * @param description 文件描述
     * @return 异步上传结果
     */
    CompletableFuture<FileUploadResponse> uploadFileAsync(MultipartFile file, Long uploaderId, String description);

    /**
     * 批量上传文件
     * @param files 上传的文件列表
     * @param uploaderId 上传者ID
     * @param descriptions 每个文件的描述（可选）
     * @return 批量上传结果
     */
    List<FileUploadResponse> uploadFiles(List<MultipartFile> files, Long uploaderId, Map<String, String> descriptions);

    /**
     * 下载文件
     * @param fileId 文件ID
     * @param userId 下载用户ID
     * @return 文件资源
     */
    Resource downloadFile(Long fileId, Long userId);

    /**
     * 获取文件信息
     * @param fileId 文件ID
     * @return 文件信息
     */
    FileStorage getFileInfo(Long fileId);

    /**
     * 删除文件
     * @param fileId 文件ID
     * @param userId 操作用户ID
     * @return 是否删除成功
     */
    boolean deleteFile(Long fileId, Long userId);

    /**
     * 分页查询文件
     * @param page 页码
     * @param size 每页大小
     * @param fileType 文件类型（可选）
     * @param uploaderId 上传者ID（可选）
     * @return 文件列表
     */
    List<FileStorage> listFiles(int page, int size, String fileType, Long uploaderId);

    /**
     * 关联文件到指定对象
     * @param fileId 文件ID
     * @param relationId 关联对象ID
     * @param relationType 关联对象类型
     * @param isPrimary 是否为主附件
     * @return 是否关联成功
     */
    boolean attachFileToEntity(Long fileId, Long relationId, String relationType, boolean isPrimary);

    /**
     * 获取对象的所有附件
     * @param relationId 关联对象ID
     * @param relationType 关联对象类型
     * @return 附件列表
     */
    List<FileStorage> getAttachments(Long relationId, String relationType);

    /**
     * 计算文件的MD5哈希值
     * @param file 文件
     * @return MD5哈希值
     */
    String calculateFileMd5(MultipartFile file);
}
